<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>pkexec</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<link rel="home" href="index.html" title="polkit Reference Manual">
<link rel="up" href="manpages.html" title="Part VI. Manual Pages">
<link rel="prev" href="pkaction.1.html" title="pkaction">
<link rel="next" href="pklocalauthority.8.html" title="pklocalauthority">
<meta name="generator" content="GTK-Doc V1.18 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
<td><a accesskey="p" href="pkaction.1.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="manpages.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">polkit Reference Manual</th>
<td><a accesskey="n" href="pklocalauthority.8.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="pkexec.1"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle">pkexec</span></h2>
<p>pkexec — Execute a command as another user</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv">
<h2>Synopsis</h2>
<div class="cmdsynopsis"><p><code class="command">pkexec</code>  [<code class="option">--version</code>] [<code class="option">--disable-internal-agent</code>] [<code class="option">--help</code>]</p></div>
<div class="cmdsynopsis"><p><code class="command">pkexec</code>  [ 
          <code class="option">--user</code>
          <em class="replaceable"><code>username</code></em>
         ]  <em class="replaceable"><code>PROGRAM</code></em>  [ <em class="replaceable"><code>ARGUMENTS</code></em> ...]</p></div>
</div>
<div class="refsect1">
<a name="pkexec-description"></a><h2>DESCRIPTION</h2>
<p>
      <span class="command"><strong>pkexec</strong></span> allows an authorized user to
      execute <em class="replaceable"><code>PROGRAM</code></em> as another
      user. If <em class="replaceable"><code>username</code></em> is not specified,
      then the program will be executed as the administrative super
      user, <span class="emphasis"><em>root</em></span>.
    </p>
</div>
<div class="refsect1">
<a name="pkexec-return-value"></a><h2>RETURN VALUE</h2>
<p>
      Upon successful completion, the return value is the return value
      of <em class="replaceable"><code>PROGRAM</code></em>. If the calling process is
      not authorized or an authorization could not be obtained through
      authentication or an error occured, <span class="command"><strong>pkexec</strong></span>
      exits with a return value of 127. If the authorization could not
      be obtained because the user dismissed the authentication
      dialog, <span class="command"><strong>pkexec</strong></span> exits with a return value of
      126.
    </p>
</div>
<div class="refsect1">
<a name="pkexec-auth-agent"></a><h2>AUTHENTICATION AGENT</h2>
<p>
      <span class="command"><strong>pkexec</strong></span>, like any other PolicyKit application,
      will use the authentication agent registered for the calling
      process. However, if no authentication agent is available, then
      <span class="command"><strong>pkexec</strong></span> will register its own textual
      authentication agent. This behavior can be turned off by passing
      the <code class="option">--disable-internal-agent</code> option.
    </p>
</div>
<div class="refsect1">
<a name="pkexec-security-notes"></a><h2>SECURITY NOTES</h2>
<p>
      Executing a program as another user is a privileged
      operation. By default the required authorization (See
      <a class="xref" href="pkexec.1.html#pkexec-required-authz" title="REQUIRED AUTHORIZATIONS">the section called “REQUIRED AUTHORIZATIONS”</a>) requires administrator
      authentication. In addition, the authentication dialog presented
      to the user will display the full path to the program to be
      executed so the user is aware of what will happen:
    </p>
<div class="mediaobject">
<a name="pkexec-bash"></a><img src="pkexec-bash.png" longdesc="pkexec-bash.html"><div class="longdesc-link" align="right">
<br clear="all"><span class="longdesc-link">[<a href="pkexec-bash.html" target="longdesc">D</a>]</span>
</div>
</div>
<p>
      The environment that <em class="replaceable"><code>PROGRAM</code></em> will run
      it, will be set to a minimal known and safe environment in order
      to avoid injecting code
      through <code class="literal">LD_LIBRARY_PATH</code> or similar
      mechanisms. In addition the <code class="literal">PKEXEC_UID</code>
      environment variable is set to the user id of the process
      invoking <span class="command"><strong>pkexec</strong></span>. As a
      result, <span class="command"><strong>pkexec</strong></span> will not allow you to run
      X11 applications as another user since
      the <code class="literal">$DISPLAY</code> and <code class="literal">$XAUTHORITY</code>
      environment variables are not set. These two variables will be retained
      if the <span class="emphasis"><em>org.freedesktop.policykit.exec.allow_gui</em></span> annotation
      on an action is set to a nonempty value; this is discouraged, though, and
      should only be used for legacy programs.
    </p>
</div>
<div class="refsect1">
<a name="pkexec-required-authz"></a><h2>REQUIRED AUTHORIZATIONS</h2>
<p>
      By default,
      the <span class="emphasis"><em>org.freedesktop.policykit.exec</em></span>
      authorization is required unless an action definition file is
      present for the program in question. To require another
      authorization, it can be specified using the <span class="emphasis"><em>org.freedesktop.policykit.exec.path</em></span> annotation on an action (See <a class="xref" href="pkexec.1.html#pkexec-example" title="EXAMPLE">the section called “EXAMPLE”</a> for details).
    </p>
</div>
<div class="refsect1">
<a name="pkexec-example"></a><h2>EXAMPLE</h2>
<p>
      To specify what kind of authorization is needed to execute the
      program <code class="filename">/usr/bin/pk-example-frobnicate</code> as
      another user, simply write an action definition file like this
    </p>
<pre class="programlisting">
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE policyconfig PUBLIC
 "-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN"
 "http://www.freedesktop.org/standards/PolicyKit/1/policyconfig.dtd"&gt;
&lt;policyconfig&gt;

  &lt;vendor&gt;Examples for the PolicyKit Project&lt;/vendor&gt;
  &lt;vendor_url&gt;http://hal.freedesktop.org/docs/PolicyKit/&lt;/vendor_url&gt;

  &lt;action id="org.freedesktop.policykit.example.pkexec.run-frobnicate"&gt;
    &lt;description&gt;Run the PolicyKit example program Frobnicate&lt;/description&gt;
    &lt;description xml:lang="da"&gt;Kør PolicyKit eksemplet Frobnicate&lt;/description&gt;
    &lt;message&gt;Authentication is required to run the PolicyKit example program Frobnicate (user=$(user), program=$(program), command_line=$(command_line))&lt;/message&gt;
    &lt;message xml:lang="da"&gt;Autorisering er påkrævet for at afvikle PolicyKit eksemplet Frobnicate (user=$(user), program=$(program), command_line=$(command_line))&lt;/message&gt;
    &lt;icon_name&gt;audio-x-generic&lt;/icon_name&gt; 
    &lt;defaults&gt;
      &lt;allow_any&gt;no&lt;/allow_any&gt;
      &lt;allow_inactive&gt;no&lt;/allow_inactive&gt;
      &lt;allow_active&gt;auth_self_keep&lt;/allow_active&gt;
    &lt;/defaults&gt;
    &lt;annotate key="org.freedesktop.policykit.exec.path"&gt;/usr/bin/pk-example-frobnicate&lt;/annotate&gt;
  &lt;/action&gt;

&lt;/policyconfig&gt;</pre>
<p>
      and drop it in the
      <code class="filename">/usr/share/polkit-1/actions</code> directory under
      a suitable name (e.g. matching the namespace of the action).
      Note that in addition to specifying the program, the
      authentication message, description, icon and defaults can be
      specified. Note that occurences of the strings
      <code class="literal">$(user)</code>, <code class="literal">$(program)</code> and
      <code class="literal">$(command_line)</code> in the message will be
      replaced with respectively the user (of the form "Real Name
      (username)" or just "username" if there is no real name for the
      username), the binary to execute (a fully-qualified path,
      e.g. "<code class="literal">/usr/bin/pk-example-frobnicate</code>") and
      the command-line, e.g. "<code class="literal">pk-example-frobnicate foo
      bar</code>". For example, for the action defined above, the
      following authentication dialog will be shown:
    </p>
<div class="mediaobject">
<a name="pkexec-frobnicate"></a><img src="pkexec-frobnicate.png" longdesc="pkexec-frobnicate.html"><div class="longdesc-link" align="right">
<br clear="all"><span class="longdesc-link">[<a href="pkexec-frobnicate.html" target="longdesc">D</a>]</span>
</div>
</div>
<p>
      If the user is using the <code class="literal">da_DK</code> locale, the
      dialog looks like this:
    </p>
<div class="mediaobject">
<a name="pkexec-frobnicate-da"></a><img src="pkexec-frobnicate-da.png" longdesc="pkexec-frobnicate-da.html"><div class="longdesc-link" align="right">
<br clear="all"><span class="longdesc-link">[<a href="pkexec-frobnicate-da.html" target="longdesc">D</a>]</span>
</div>
</div>
<p>
      Note that <span class="command"><strong>pkexec</strong></span> does no validation of
      the <em class="replaceable"><code>ARGUMENTS</code></em> passed
      to <em class="replaceable"><code>PROGRAM</code></em>. In the normal case (where
      administrator authentication is required every
      time <span class="command"><strong>pkexec</strong></span> is used), this is not a problem
      since if the user is an administrator he might as well just
      run <span class="command"><strong>pkexec bash</strong></span> to get root.
    </p>
<p>
      However, if an action is used for which the user can retain
      authorization (or if the user is implicitly authorized), such as
      with <code class="filename">pk-example-frobnicate</code> above, this
      could be a security hole. Therefore, as a rule of thumb,
      programs for which the default required authorization is
      changed, should never implicitly trust user input (e.g. like any
      other well-written <span class="emphasis"><em>suid</em></span> program).
    </p>
</div>
<div class="refsect1">
<a name="pkexec-author"></a><h2>AUTHOR</h2>
<p>
      Written by David Zeuthen <code class="email">&lt;<a class="email" href="mailto:davidz@redhat.com">davidz@redhat.com</a>&gt;</code> with
      a lot of help from many others.
    </p>
</div>
<div class="refsect1">
<a name="pkexec-bugs"></a><h2>BUGS</h2>
<p>
      Please send bug reports to either the distribution or the
      polkit-devel mailing list,
      see the link <a class="ulink" href="http://lists.freedesktop.org/mailman/listinfo/polkit-devel" target="_top">http://lists.freedesktop.org/mailman/listinfo/polkit-devel</a>
      on how to subscribe.
    </p>
</div>
<div class="refsect1">
<a name="pkexec-see-also"></a><h2>SEE ALSO</h2>
<p>
      <span class="citerefentry"><span class="refentrytitle">polkit</span>(8)</span>,
      <span class="citerefentry"><span class="refentrytitle">pkaction</span>(1)</span>,
      <span class="citerefentry"><span class="refentrytitle">pkcheck</span>(1)</span>,
      <span class="citerefentry"><span class="refentrytitle">pkttyagent</span>(1)</span>
    </p>
</div>
</div>
<div class="footer">
<hr>
          Generated by GTK-Doc V1.18</div>
</body>
</html>